Prizm Content Connect
How to Transfer Your Document to PCCIS
| User Guides > PCC Imaging Services (PCCIS) > How To's for PCC Imaging Services (PCCIS) > How To's for the Imaging Service > How to Transfer Your Document to PCCIS |
Once a viewing session is created, PCCIS will expect a source document to be provided or made available by one of three methods. The specific method of transfer used for a particular document is specified during the creation of the viewing session, so it is possible to use multiple transfer methods in your application. You can transfer your documents to PCCIS by sending it explicitly with a HTTP PUT request or by specifying an HTTP URL or local filename so that PCCIS can retrieve it.
Ultimately, the best transfer method for your application will likely depend on the original location of your documents. For example, if your source documents are stored in a database, the HTTP PUT request is likely the most efficient method as you’ll be able to read the data out of the database and copy it directly to the request body, eliminating the need to write the document to a file. If your source documents are already hosted and accessible from an HTTP URL, PCCIS can download the file directly thus eliminating any intermediate transfers. Finally, if your source documents already exist on the server that is hosting PCCIS then providing the local path to each file is a good option.
The following sections provide some specific information about each transfer method.
This is considered the default method of transferring source documents to PCCIS. It provides the most independent method of transferring documents because the data is sent directly to PCCIS, largely reducing the chances of a failure as compared to the other methods.
The request has the following format:
PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}
The document data should be included directly in the request body. This request should be made after the HTTP POST request to create a viewing session and before the HTTP POST to start a viewing session.
PCCIS supports downloading a document from a HTTP or HTTPS URL. The URL must either be publicly accessible, or at least accessible over the internal network to which PCCIS is connected.
The HTTP PUT request is not required with this transfer method. Instead, some JSON properties in the body of the HTTP POST request to create a new viewing session must be set appropriately. These specific properties are described below. See the PCCIS RESTful Web API topic for more details about other JSON properties set in this request.
To enable the HTTP URL transfer method, set the “documentSource” JSON property to “http”. This will inform PCCIS to expect a valid URL to be specified by the “externalId” JSON property. Set the “externalId” JSON property to the HTTP URL of your document. PCCIS will require a valid extension be provided as well. You can set the extension explicitly with the “documentExtension” JSON property. If “documentExtension” is not set, PCCIS will attempt to extract an extension from the end of the URL resource name.
When PCCIS receives the POST request to create the viewing session, it will begin downloading the document asynchronously in a background thread while the request returns with a status of OK. Because the document download occurs asynchronously within PCCIS, it is possible that the retrieval process will fail without any explicit feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of “Document download failed”.
There is a user-configurable timeout value that PCCIS will use when it sends the GET HTTP request to download the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the pcc.config description topic for details about other user-configurable properties.
For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the “externalId” JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the the pcc.config description topic for details about this and other configuration properties.
The third option to transfer documents makes use of the local file system to make your documents available to PCCIS. This option is enabled by setting the “documentSource” JSON property to “file”. This will inform PCCIS to expect a valid local file name to be specified by the “externalId” JSON property. Set the “externalId” JSON property to the filename of your document. PCCIS will require a valid extension be provided as well. You can set the extension explicitly with the “documentExtension” JSON property. If “documentExtension” is not set, PCCIS will attempt to extract an extension from the end of the filename given.
For security purposes, only partial/relative paths and filenames are supported in “externalId”. Rooted paths are not supported. Instead, the root directory where your documents will exist should be specified in pcc.config using the UserDocumentFolder property. PCCIS will combine the root directory in this property with the value it receives in “externalId”. If, when combined, a relative path in “externalId” takes the current directory outside of the directory specified in UserDocumentFolder, or any other invalid path is used, the transfer will fail.
The following are examples of valid values for “externalId”:
When PCCIS receives the POST request to create the viewing session, it will copy the document asynchronously in a background thread while the request returns with a status of OK. Because the document is copied asynchronously within PCCIS, it is possible that the retrieval process will fail without any explicit feedback. In this case, the viewing session will be stopped, and any request in the context of the same viewing session will return in error with a status code of 580 and HTTP reason of “Document download failed”.
Finally, there is a user-configurable timeout value that PCCIS will use when it copies the document. This timeout value is specified in pcc.config under the property DocumentAcquisitionTimeout. The default value is 25 seconds. See the the pcc.config description topic for details about other user-configurable properties.
For additional security, there is a user-configurable property in pcc.config called ViewingSessionPropertyExternalId that can be used to restrict values coming in from the “externalId” JSON property. Any values that do not pass this filter will cause the viewing session to be stopped immediately. See the the pcc.config description topic for details about this and other configuration properties.